home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / cocktail / docme.lha / doc.me / reuse.me < prev    next >
Text File  |  1992-09-25  |  52KB  |  1,544 lines
  1. .\" use: pic | tbl | eqn | ditroff -me
  2. .\"
  3. .\"    "@(#)bibmac.me    2.2    9/9/83";
  4. .de IP
  5. .ip \\$1 \\$2
  6. ..
  7. .de LP
  8. .lp
  9. ..
  10. .\"    @(#)bmac.std    2.2    9/9/83;
  11. .\" standard format troff commands
  12. .\" citation formatting strings
  13. .ds [[ [
  14. .ds ]] ]
  15. .ds ], ,\|
  16. .ds ]- -
  17. .ds [. " \&
  18. .ds .] .
  19. .ds [, " \&
  20. .ds ,] ,
  21. .ds [? " \&
  22. .ds ?] ?
  23. .ds [: " \&
  24. .ds :] :
  25. .ds [; " \&
  26. .ds ;] ;
  27. .ds [! " \&
  28. .ds !] !
  29. .ds [" " \&
  30. .ds "] \&"
  31. .ds [' " \&
  32. .ds '] '
  33. .ds [< " \&
  34. .ds >]
  35. .\" reference formmating strings
  36. .ds a] " \&
  37. .ds b] , \&
  38. .ds c] , \&
  39. .ds n] "\& and \&
  40. .ds m] "\& and \&
  41. .ds p] .
  42. .\" reference formmating macros
  43. .de s[   \" start reference
  44. .nh
  45. .IP [\\*([F] 5m
  46. ..
  47. .de e[   \" end reference
  48. .[-
  49. ..
  50. .de []   \" start to display collected references
  51. .LP
  52. ..
  53. .de ][   \" choose format
  54. .ie !"\\*([J"" \{\
  55. .    ie !"\\*([V"" .nr t[ 1    \" journal
  56. .    el            .nr t[ 5    \" conference paper
  57. .\}
  58. .el .ie !"\\*([B"" .nr t[ 3    \" article in book
  59. .el .ie !"\\*([R"" .nr t[ 4    \" technical report
  60. .el .ie !"\\*([I"" .nr t[ 2    \" book
  61. .el                .nr t[ 0    \" other
  62. .\\n(t[[
  63. ..
  64. .de 0[   \" other
  65. .s[
  66. .if !"\\*([A"" \\*([A\\c
  67. .if !"\\*([T"" , \\*([T\\c
  68. .if !"\\*([V"" , Vol. \\*([V\\c
  69. .if !"\\*([O"" , \\*([O\\c
  70. .if !"\\*([D"" , \\*([D\\c
  71. \&.
  72. .e[
  73. ..
  74. .de 1[ \" journal article
  75. .s[
  76. .if !"\\*([A"" \\*([A,
  77. .if !"\\*([T""  \\*([T,
  78. \\fI\\*([J \\*([V\\fP\c
  79. .if !"\\*([N"" ,\\*([N
  80. .if !"\\*([D"" (\\*([D)\c
  81. .if !"\\*([P"" , \\*([P\c
  82. .if !"\\*([I"" , \\*([I\c
  83. \\&.
  84. .if !"\\*([O"" \\*([O.
  85. .e[
  86. ..
  87. .de 2[ \" book
  88. .s[
  89. .ie !"\\*([A"" \\*([A,
  90. .el .if !"\\*([E"" \{\
  91. .       ie \\n([E-1 \\*([E, eds.,
  92. .       el \\*([E, ed.,\}
  93. .if !"\\*([T"" \\fI\\*([T\\fP,
  94. .rm a[
  95. .if !"\\*([I"" .ds a[ \\*([I
  96. .if !"\\*([C"" \{\
  97. .       if !"\\*(a["" .as a[ , \\&
  98. .       as a[ \\*([C\}
  99. .if !"\\*([D"" \{\
  100. .       if !"\\*(a["" .as a[ , \\&
  101. .       as a[ \\*([D\}
  102. \\*(a[.
  103. .if !"\\*([G"" Gov. ordering no. \\*([G.
  104. .if !"\\*([O"" \\*([O.
  105. .e[
  106. ..
  107. .de 3[ \" article in book
  108. .s[
  109. .if !"\\*([A"" \\*([A,
  110. .if !"\\*([T"" \\*([T,
  111. in \\fI\\*([B\\fP\c
  112. .if !"\\*([V"" , vol. \\*([V
  113. .if !~\\*([E~~ \{\
  114. .       ie , \\n([E-1  \\*([E (editors)\c
  115. .       el , \\*([E (editor)\c\}
  116. .if !"\\*([I"" , \\*([I\c
  117. .if !"\\*([C"" , \\*([C\c
  118. .if !"\\*([D"" , \\*([D\c
  119. .if !"\\*([P"" , \\*([P\c
  120. \\&.
  121. .if !"\\*([O"" \\*([O.
  122. .e[
  123. ..
  124. .de 4[ \" report
  125. .s[
  126. .if !"\\*([A"" \\*([A,
  127. .if !~\\*([E~~ \{\
  128. .       ie \\n([E-1 \\*([E, editors.
  129. .       el \\*([E, editor.\}
  130. \\*([T,
  131. \\*([R\c
  132. .if !"\\*([G"" \& (\\*([G)\c
  133. .if !"\\*([I"" , \\*([I\c
  134. .if !"\\*([C"" , \\*([C\c
  135. .if !"\\*([D"" , \\*([D\c
  136. \\&.
  137. .if !"\\*([O"" \\*([O.
  138. .e[
  139. ..
  140. .de 5[ \" conference paper
  141. .s[
  142. .if !"\\*([A"" \\*([A,
  143. .if !"\\*([T"" \\*([T,
  144. \\fI\\*([J\\fP,
  145. .if !"\\*([C"" \\*([C,
  146. .if !"\\*([D"" \\*([D\c
  147. .if !"\\*([P"" , \\*([P\c
  148. \\&.
  149. .if !"\\*([O"" \\*([O.
  150. .e[
  151. ..
  152. .de [-   \" clean up after yourself
  153. .rm [A [B [C [D
  154. .rm [E [F [G
  155. .rm [I [J [K
  156. .rm [N [O [P
  157. .rm [R [T
  158. .rm [V [W
  159. ..
  160. .\"    @(#)bmac.std    2.2    8/24/83;
  161. .\" standard format troff commands
  162. .\" citation formatting strings
  163. .ds [[ [
  164. .ds ]] ]
  165. .ds ], ,\|
  166. .ds ]- -
  167. .ds [. " \&
  168. .ds .] .
  169. .ds [, " \&
  170. .ds ,] ,
  171. .ds [< " \&
  172. .ds >]
  173. .\" reference formmating strings
  174. .ds c] , \&
  175. .ds n] "" and \&
  176. .ds m] "" and \&
  177. .ds a] " \&
  178. .\" reference formmating macros
  179. .de s[   \" start reference
  180. .nh
  181. .IP [\\*([F] 5m
  182. ..
  183. .de e[   \" end reference
  184. .[-
  185. ..
  186. .de []   \" start to display collected references
  187. .SH
  188. References
  189. .LP
  190. ..
  191. .de ][   \" choose format
  192. .ie !"\\*([J"" \{\
  193. .    ie !"\\*([V"" .nr t[ 1    \" journal
  194. .    el            .nr t[ 5    \" conference paper
  195. .\}
  196. .el .ie !"\\*([B"" .nr t[ 3    \" article in book
  197. .el .ie !"\\*([R"" .nr t[ 4    \" technical report
  198. .el .ie !"\\*([I"" .nr t[ 2    \" book
  199. .el                .nr t[ 0    \" other
  200. .\\n(t[[
  201. ..
  202. .de 0[   \" other
  203. .s[
  204. .if !"\\*([A"" \\*([A,
  205. .if !"\\*([T"" \\*([T,
  206. .if !"\\*([O"" \\*([O\c
  207. .if !"\\*([D"" , \\*([D\c
  208. \&.
  209. .e[
  210. ..
  211. .de 1[ \" journal article
  212. .s[
  213. .if !"\\*([A"" \\*([A,
  214. .if !"\\*([T"" \\*([T,
  215. \\fI\\*([J \\*([V\\fP,
  216. .if !"\\*([N"" \\*([N
  217. .if !"\\*([D"" (\\*([D),
  218. .if !"\\*([P"" \\*([P\c
  219. .if !"\\*([I"" , \\*([I\c
  220. \\&.
  221. .if !"\\*([O"" \\*([O.
  222. .e[
  223. ..
  224. .de 2[ \" book
  225. .s[
  226. .ie !"\\*([A"" \\*([A,
  227. .el .if !"\\*([E"" \{\
  228. .       ie \\n([E-1 \\*([E, eds.,
  229. .       el \\*([E, ed.,\}
  230. .if !"\\*([T"" \\fI\\*([T\\fP,
  231. .rm a[
  232. .if !"\\*([I"" .ds a[ \\*([I
  233. .if !"\\*([C"" \{\
  234. .       if !"\\*(a["" .as a[ , \\&
  235. .       as a[ \\*([C\}
  236. .if !"\\*([D"" \{\
  237. .       if !"\\*(a["" .as a[ , \\&
  238. .       as a[ \\*([D\}
  239. \\*(a[.
  240. .if !"\\*([G"" Gov. ordering no. \\*([G.
  241. .if !"\\*([O"" \\*([O.
  242. .e[
  243. ..
  244. .de 3[ \" article in book
  245. .s[
  246. .if !"\\*([A"" \\*([A,
  247. .if !"\\*([T"" \\*([T,
  248. in \\fI\\*([B\\fP,
  249. .if !"\\*([V"" vol. \\*([V,
  250. .if !"\\*([E"" \\*([E (ed.),
  251. .if !"\\*([I"" \\*([I,
  252. .if !"\\*([C"" \\*([C,
  253. .if !"\\*([D"" \\*([D\c
  254. .if !"\\*([P"" , \\*([P\c
  255. \\&.
  256. .if !"\\*([O"" \\*([O.
  257. .e[
  258. ..
  259. .de 4[ \" report
  260. .s[
  261. .if !"\\*([A"" \\*([A,
  262. \\*([T,
  263. \\*([R\c
  264. .if !"\\*([G"" \& (\\*([G)\c
  265. .if !"\\*([I"" , \\*([I\c
  266. .if !"\\*([C"" , \\*([C\c
  267. .if !"\\*([D"" , \\*([D\c
  268. \\&.
  269. .if !"\\*([O"" , \\*([O.
  270. .e[
  271. ..
  272. .de 5[ \" conference paper
  273. .s[
  274. .if !"\\*([A"" \\*([A,
  275. .if !"\\*([T"" \\*([T,
  276. \\fI\\*([J\\fP,
  277. .if !"\\*([C"" \\*([C\c
  278. .if !"\\*([D"" , \\*([D\c
  279. .if !"\\*([P"" , \\*([P\c
  280. \\&.
  281. .if !"\\*([O"" , \\*([O.
  282. .e[
  283. ..
  284. .de [-   \" clean up after yourself
  285. .rm [A [B [C [D
  286. .rm [E [F [G
  287. .rm [I [J [K
  288. .rm [N [O [P
  289. .rm [R [T
  290. .rm [V [W
  291. ..
  292. .if t \{ \
  293. .pl 29.7c    \" page length
  294. .po 2.5c    \" page offset (left margin)
  295. .ll 16.5c    \" line length
  296. .lt 16.5c    \" title length
  297. .nr LL 16.5c
  298. .nr )l 29.7c
  299. .nr hm 2c
  300. .nr $r 9    \" factor for vertical spacing
  301. .nr $R \n($r
  302. .sz 12        \" font size
  303. .nr pp 12
  304. .nr sp 12
  305. .nr tp 12
  306. .nr fp 10
  307. .hc ~        \" hyphenation character
  308. .        \" Umlauts and sharp s
  309. .ds A \(A:
  310. .ds O \(O:
  311. .ds U \(U:
  312. .ds a \(a:
  313. .ds o \(o:
  314. .ds u \(u:
  315. .ds s \(ss
  316. .        \"  UMLAUT  \*:u, etc.
  317. .ds : \v'-0.6m'\h'(1u-(\\n(.fu%2u))*0.13m+0.06m'\z.\h'0.2m'\z.\h'-((1u-(\\n(.fu%2u))*0.13m+0.26m)'\v'0.6m'
  318. .\}
  319. .if n \{ \
  320. .po 0        \" page offset (left margin)
  321. .ll 78        \" line length
  322. .lt 78        \" title length
  323. .nr $r 4    \" factor for vertical spacing
  324. .nr $R \n($r
  325. .hc ~        \" hyphenation character
  326. .        \" Umlaute und scharfes s
  327. .ds A Ae
  328. .ds O Oe
  329. .ds U Ue
  330. .ds a ae
  331. .ds o oe
  332. .ds u ue
  333. .ds s sz
  334. .\}
  335. .de _
  336. \&\\$1\l'|0\(ul'\\$2
  337. ..
  338. .de FT        \" font for programs
  339. .ft C
  340. .sz -2
  341. ..
  342. .de FR
  343. .ft R
  344. .sz +2
  345. ..
  346. .de []        \" start to display collected references
  347. .uh References
  348. .lp
  349. ..
  350. .de $0        \" collect table of contents
  351. .(x
  352. .ta 2c
  353. .ie '\\$2''    \\$1
  354. .el \\$2.    \\$1
  355. .)x
  356. ..
  357. .de np
  358. .nr $p +1
  359. .ip \\n($p.
  360. ..
  361. .de SH
  362. .sp 0.5
  363. .in -3
  364. .r \\$1
  365. .sp 0.5
  366. .in +3
  367. ..
  368. .de PP
  369. .sp 0.5
  370. ..
  371. .de IP
  372. .ip \\$1 \\$2
  373. ..
  374. .de I
  375. .i \\$1
  376. ..
  377. .de TH
  378. ..
  379. .EQ
  380. delim $$
  381. gsize 12
  382. gfont R
  383. .EN
  384. .b " "
  385. .sp 1c
  386. .ta 9c
  387. .ft R
  388. .sz 12
  389. \l'17.1c'
  390. .nf
  391.  
  392.  
  393.     Reusable Software
  394.     A Collection of MODULA-Modules
  395.  
  396.     J. Grosch
  397.  
  398.  
  399. \l'17.1c'
  400. .sp 12.5c
  401. \l'17.1c'
  402. .ft H
  403. .nf
  404.     GESELLSCHAFT F\*UR MATHEMATIK
  405.     UND DATENVERARBEITUNG MBH
  406.  
  407.     FORSCHUNGSSTELLE F\*UR
  408.     PROGRAMMSTRUKTUREN
  409.     AN DER UNIVERSIT\*AT KARLSRUHE
  410. .r
  411. \l'17.1c'
  412. .bp
  413. .oh ''Reuse'%'
  414. .eh ''Reuse'%'
  415. .nr % 0
  416. .ce 99
  417. .sz 20
  418. .b " "
  419. .sp 2
  420. Project
  421. .sp
  422. .b "Compiler Generation"
  423. .sp
  424. .sz 12
  425. \l'15c'
  426. .sp
  427. .sz 16
  428. .b "Reusable Software"
  429. .b "A Collection of MODULA-Modules"
  430. .sp 2
  431. Josef Grosch
  432. .sp 2
  433. .sz 14
  434. Aug. 4 1992
  435. .sp
  436. .sz 12
  437. \l'15c'
  438. .sp 2
  439. Report No. 4
  440. .sp 2
  441. Copyright \(co 1992 GMD
  442. .sp 2
  443. Gesellschaft f\*ur Mathematik und Datenverarbeitung mbH
  444. Forschungsstelle an der Universit\*at Karlsruhe
  445. Vincenz-Prie\*snitz-Str. 1
  446. D-7500 Karlsruhe
  447. .ce 0
  448. .bp 2
  449. .uh Abstract
  450. .lp
  451. A brief description of my personal collection of reusable modules written
  452. in MODULA-2 is given.
  453. Some modules have been translated to the language C.
  454. .sh 1 Overview
  455. .pp
  456. The following modules exist currently (Aug. 1992):
  457. .sp 0.5
  458. .TS
  459. box center;
  460. l l.
  461. Module    Task
  462. _
  463. Memory    dynamic storage (heap) with free lists
  464. Heap    dynamic storage (heap) without free lists
  465. DynArray    dynamic and flexible arrays
  466. Strings    string handling
  467. StringMem    string memory
  468. Idents    identifier table - unambiguous encoding of strings
  469. Lists    lists of arbitrary objects
  470. Texts    texts are lists of strings (lines)
  471. Sets    sets of scalar values (without run time checks)
  472. SetsC    sets of scalar values (with run time checks)
  473. Relations    binary relations between scalar values
  474. IO    buffered input and output
  475. StdIO    buffered IO for standard files
  476. Layout    more routines for input and output
  477. Positions    handling of source positions
  478. Errors    error handler for parsers and compilers
  479. Source    provides input for scanners
  480. Sort    quicksort for arrays with elements of arbitrary type
  481. General    miscellaneous functions
  482. System    machine dependent code
  483. Checks    checks for system calls
  484. Times    access to cpu-time
  485. .TE
  486. .sh 1 "Memory: dynamic storage (heap) with free lists"
  487. .sp
  488. .(b L
  489. .FT
  490. DEFINITION MODULE Memory;
  491.  
  492. VAR       MemoryUsed    : LONGCARD;
  493.                         (* Holds the total amount of memory managed by  *)
  494.                         (* this module.                                 *)
  495.  
  496. PROCEDURE Alloc         (ByteCount: LONGINT) : ADDRESS;
  497.                         (* Returns a pointer to dynamically allocated   *)
  498.                         (* memory space of size 'ByteCount' bytes.      *)
  499.                         (* Returns NIL if space is exhausted.           *)
  500.  
  501. PROCEDURE Free          (ByteCount: LONGINT; a: ADDRESS);
  502.                         (* The dynamically allocated space starting at  *)
  503.                         (* address 'a' of size 'ByteCount' bytes is     *)
  504.                         (* released.                                    *)
  505.  
  506. END Memory.
  507. .)b
  508. .bp
  509. .sh 1 "Heap: dynamic storage (heap) without free lists"
  510. .sp
  511. .(b L
  512. .FT
  513. DEFINITION MODULE Heap;
  514.  
  515. VAR       HeapUsed      : LONGCARD;
  516.                         (* Holds the total amount of memory managed by  *)
  517.                         (* this module.                                 *)
  518.  
  519. PROCEDURE Alloc         (ByteCount: LONGINT) : ADDRESS;
  520.                         (* Returns a pointer to dynamically allocated   *)
  521.                         (* space of size 'ByteCount' bytes.             *)
  522.  
  523. PROCEDURE Free          ;
  524.                         (* The complete space allocated for the heap    *)
  525.                         (* is released.                                 *)
  526.  
  527. END Heap.
  528. .)b
  529. .sh 1 "DynArray: dynamic and flexible arrays"
  530. .pp
  531. This module provides dynamic and flexible arrays. The size of a dynamic
  532. array is determined at run time. It must be passed to a procedure to
  533. create the array. The size of such an array is also flexible, that means it
  534. can grow to arbitrary size by repeatedly calling a procedure to extend it.
  535. .sp
  536. .(b L
  537. .FT
  538. DEFINITION MODULE DynArray;
  539.  
  540. PROCEDURE MakeArray     (VAR ArrayPtr   : ADDRESS       ;
  541.                          VAR ElmtCount  : LONGINT       ;
  542.                              ElmtSize   : LONGINT)      ;
  543.                         (* 'ArrayPtr' is set to the start address of a  *)
  544.                         (* memory space to hold an array of 'ElmtCount' *)
  545.                         (* elements each of size 'ElmtSize' bytes.      *)
  546.  
  547. PROCEDURE ExtendArray   (VAR ArrayPtr   : ADDRESS       ;
  548.                          VAR ElmtCount  : LONGINT       ;
  549.                              ElmtSize   : LONGINT)      ;
  550.                         (* The memory space for the array is increased  *)
  551.                         (* by doubling the number of elements.          *)
  552.  
  553. PROCEDURE ReleaseArray  (VAR ArrayPtr   : ADDRESS       ;
  554.                          VAR ElmtCount  : LONGINT       ;
  555.                              ElmtSize   : LONGINT)      ;
  556.                         (* The memory space for the array is released.  *)
  557.  
  558. END DynArray.
  559. .)b
  560. .lp
  561. Example:
  562. .sp 0.5
  563. There is a problem with the index arithmetic generated by the compiler.
  564. If TSIZE (ArrayType) < 65536 then index arithmetic will be done with 2 byte
  565. values otherwise with 4 byte values.
  566. Arithmetic with 2 bytes allows only access to arrays whose size never
  567. exceeds 65536 bytes.
  568. If larger arrays are desired then ArrayType has to be declared to yield a
  569. size greater or equal to 65536 bytes like below.
  570. .sp
  571. .(b L
  572. .FT
  573. CONST InitialSize       = 100;
  574. TYPE  ElmtType          = ... ;
  575. TYPE  ArrayType         = ARRAY [0 .. 100000] OF ElmtType;
  576. VAR   ActualSize        : LONGINT;
  577. VAR   ArrayPtr          : POINTER TO ArrayType;
  578.  
  579. BEGIN
  580.    ActualSize := InitialSize;
  581.    MakeArray (ArrayPtr, ActualSize, TSIZE (ElmtType));
  582.  
  583.    (* Case 1: continuously growing array *)
  584.  
  585.    Index := 0;
  586.    LOOP
  587.       INC (Index);
  588.       IF Index = ActualSize THEN
  589.          ExtendArray (ArrayPtr, ActualSize, TSIZE (ElmtType));
  590.       END;
  591.  
  592.       ArrayPtr ^ [Index] := ... ;   (* access an array element *)
  593.        ... := ArrayPtr ^ [Index];   (* "      "  "     "       *)
  594.    END;
  595.  
  596.    (* Case 2: non-continuously growing array *)
  597.  
  598.    LOOP
  599.       Index := ... ;
  600.       WHILE Index >= ActualSize DO
  601.          ExtendArray (ArrayPtr, ActualSize, TSIZE (ElmtType));
  602.       END;
  603.  
  604.       ArrayPtr ^ [Index] := ... ;   (* access an array element *)
  605.        ... := ArrayPtr ^ [Index];   (* "      "  "     "       *)
  606.    END;
  607.  
  608.    ReleaseArray (ArrayPtr, ActualSize, TSIZE (ElmtType));
  609. END;
  610. .)b
  611. .bp
  612. .sh 1 "Strings: string handling"
  613. .pp
  614. This module provides operations on strings whose length is at most 255 characters.
  615. .sp
  616. .(l L
  617. .FT
  618. DEFINITION MODULE Strings;
  619.  
  620. CONST   cMaxStrLength   = 255;
  621.  
  622. TYPE    tString         ;
  623. TYPE    tStringIndex    = [0 .. cMaxStrLength];
  624.  
  625. PROCEDURE Assign        (VAR s1, s2: tString);
  626.                         (* Assigns the string 's2' to the string 's1'.  *)
  627.  
  628. PROCEDURE AssignEmpty   (VAR s: tString);
  629.                         (* Returns an empty string 's'.                 *)
  630.  
  631. PROCEDURE Concatenate   (VAR s1, s2: tString);
  632.                         (* Returns in parameter 's1' the concatenation  *)
  633.                         (* of the strings 's1' and 's2'.                *)
  634.  
  635. PROCEDURE Append        (VAR s: tString; c: CHAR);
  636.                         (* The character 'c' is concatenated at the end *)
  637.                         (* of the string 's'.                           *)
  638.  
  639. PROCEDURE Length        (VAR s: tString)                        : CARDINAL;
  640.                         (* Returns the length of the string 's'.        *)
  641.  
  642. PROCEDURE IsEqual       (VAR s1, s2: tString)                   : BOOLEAN;
  643.                         (* Returns TRUE if the strings 's1' and 's2'    *)
  644.                         (* are equal.                                   *)
  645.  
  646. PROCEDURE IsInOrder     (VAR s1, s2: tString)                   : BOOLEAN;
  647.                         (* Returns TRUE if the string 's1' is lexico-   *)
  648.                         (* graphically less or equal to the string 's2'.*)
  649.  
  650. PROCEDURE Exchange      (VAR s1, s2: tString);
  651.                         (* Exchanges the strings 's1' and 's2'.         *)
  652.  
  653. PROCEDURE SubString     (VAR s1: tString; from, to: tStringIndex; VAR s2: tString);
  654.                         (* Returns in 's2' the substring from 's1' com- *)
  655.                         (* prising the characters between 'from' and 'to'. *)
  656.                         (* PRE  1 <= from <= Length (s1)                *)
  657.                         (* PRE  1 <=  to  <= Length (s1)                *)
  658.  
  659. PROCEDURE Char          (VAR s: tString; i: tStringIndex)       : CHAR;
  660.                         (* Returns the 'i'-th character of the string 's'. *)
  661.                         (* The characters are counted from 1 to Length (s). *)
  662.                         (* PRE  1 <= index <= Length (s)                *)
  663.  
  664. PROCEDURE ArrayToString (a: ARRAY OF CHAR; VAR s: tString);
  665.                         (* An array 'a' of characters representing a    *)
  666.                         (* MODULA string is converted to a string 's'   *)
  667.                         (* of type tString.                             *)
  668.  
  669. PROCEDURE StringToArray (VAR s: tString; VAR a: ARRAY OF CHAR);
  670.                         (* A string 's' of type tString is converted to *)
  671.                         (* an array 'a' of characters representing a    *)
  672.                         (* MODULA string.                               *)
  673.  
  674. PROCEDURE StringToInt   (VAR s: tString)                        : INTEGER;
  675.                         (* Returns the integer value represented by 's'. *)
  676.  
  677. PROCEDURE StringToNumber(VAR s: tString; Base: CARDINAL)        : CARDINAL;
  678.                         (* Returns the integer value represented by 's' *)
  679.                         (* to the base 'Base'.                          *)
  680.  
  681. PROCEDURE StringToReal  (VAR s: tString)                        : REAL;
  682.                         (* Returns the real value represented by 's'.   *)
  683.  
  684. PROCEDURE IntToString   (n: INTEGER; VAR s: tString);
  685.                         (* Returns in 's' the string representation of 'n'. *)
  686.  
  687. PROCEDURE ReadS         (f: tFile; VAR s: tString; FieldWidth: tStringIndex);
  688.                         (* Read 'FieldWidth' characters as string 's'   *)
  689.                         (* from file 'f'.                               *)
  690.  
  691. PROCEDURE ReadL         (f: tFile; VAR s: tString);
  692.                         (* Read rest of line as string 's' from file    *)
  693.                         (* 'f'. Skip to next line.                      *)
  694.  
  695. PROCEDURE WriteS        (f: tFile; VAR s: tString);
  696.                         (* Write string 's' to file 'f'.                *)
  697.  
  698. PROCEDURE WriteL        (f: tFile; VAR s: tString);
  699.                         (* Write string 's' as complete line.           *)
  700.  
  701. END Strings.
  702. .)l
  703. .bp
  704. .sh 1 "StringMem: string memory"
  705. .sp
  706. .(b L
  707. .FT
  708. DEFINITION MODULE StringMem;
  709.  
  710. TYPE tStringRef         ;
  711.  
  712. PROCEDURE PutString     (VAR s: tString)                        : tStringRef;
  713.                         (* Stores string 's' in the string memory and   *)
  714.                         (* returns a reference to the stored string.    *)
  715.  
  716. PROCEDURE GetString     (r: tStringRef;                    VAR s: tString);
  717.                         (* Returns the string 's' from the string       *)
  718.                         (* memory which is referenced by 'r'.           *)
  719.  
  720. PROCEDURE Length        (r: tStringRef)                         : CARDINAL;
  721.                         (* Returns the length of the string 's'         *)
  722.                         (* which is referenced by 'r'.                  *)
  723.  
  724. PROCEDURE IsEqual       (r: tStringRef; VAR s: tString)         : BOOLEAN;
  725.                         (* Compares the string referenced by 'r' and    *)
  726.                         (* the string 's'.                              *)
  727.                         (* Returns TRUE if both are equal.              *)
  728.  
  729. PROCEDURE WriteString   (f: tFile; r: tStringRef);
  730.                         (* The string referenced by 'r' is printed on   *)
  731.                         (* the file 'f'.                                *)
  732.  
  733. PROCEDURE WriteStringMemory;
  734.                         (* The contents of the string memory is printed *)
  735.                         (* on the file 'StdOutput'.                     *)
  736.  
  737. PROCEDURE InitStringMemory;
  738.                         (* The string memory is initialized.            *)
  739.  
  740. END StringMem.
  741. .)b
  742. .bp
  743. .sh 1 "Idents: identifier table - unambiguous encoding of strings"
  744. .sp
  745. .(b L
  746. .FT
  747. DEFINITION MODULE Idents;
  748.  
  749. TYPE      tIdent        ;
  750.  
  751. VAR       NoIdent       : tIdent;       (* a default (empty) identifier *)
  752.  
  753. PROCEDURE MakeIdent     (VAR s: tString)                : tIdent;
  754.                         (* The string 's' is mapped to a unique         *)
  755.                         (* identifier (an integer) which is returned.   *)
  756.  
  757. PROCEDURE GetString     (i: tIdent; VAR s: tString);
  758.                         (* Returns the string 's' whose identifier is 'i'. *)
  759.  
  760. PROCEDURE GetStringRef  (i: tIdent)                     : tStringRef;
  761.                         (* Returns a reference to a string whose        *)
  762.                         (* identifier is 'i'.                           *)
  763.  
  764. PROCEDURE MaxIdent      ()                              : tIdent;
  765.                         (* Returns the current maximal value of the     *)
  766.                         (* type 'tIdent'.                               *)
  767.  
  768. PROCEDURE WriteIdent    (f: tFile; i: tIdent);
  769.                         (* The string encoded by the identifier 'i' is  *)
  770.                         (* printed on the file 'f'.                     *)
  771.  
  772. PROCEDURE WriteIdents   ;
  773.                         (* The contents of the identifier table is      *)
  774.                         (* printed on the file 'StdOutput'.             *)
  775.  
  776. PROCEDURE InitIdents    ;
  777.                         (* The identifier table is initialized.         *)
  778.  
  779. END Idents.
  780. .)b
  781. .bp
  782. .sh 1 "Lists: lists of arbitrary objects"
  783. .pp
  784. This module actually handles lists of untyped pointers.
  785. Thus it is possible to have lists of pointers referring to objects of arbitrary types.
  786. .sp
  787. .(b L
  788. .FT
  789. DEFINITION MODULE Lists;
  790.  
  791. TYPE tList              ;
  792.  
  793. PROCEDURE MakeList      (VAR List: tList);
  794.                         (* Create an empty list.                        *)
  795.  
  796. PROCEDURE Insert        (VAR List: tList; Elmt: ADDRESS);
  797.                         (* Add element at the beginning of the list.    *)
  798.  
  799. PROCEDURE Append        (VAR List: tList; Elmt: ADDRESS);
  800.                         (* Add element at the end of the list.          *)
  801.  
  802. PROCEDURE Head          (    List: tList): ADDRESS;
  803.                         (* Return first element of the list.            *)
  804.  
  805. PROCEDURE Tail          (VAR List: tList);
  806.                         (* Return list except first element.            *)
  807.  
  808. PROCEDURE Last          (    List: tList): ADDRESS;
  809.                         (* Return last element of the list.             *)
  810.  
  811. PROCEDURE Front         (VAR List: tList);
  812.                         (* Return list except last element.             *)
  813.                         (* Not implemented.                             *)
  814.  
  815. PROCEDURE IsEmpty       (    List: tList): BOOLEAN;
  816.                         (* Returns TRUE if the list is empty.           *)
  817.  
  818. PROCEDURE Length        (    List: tList): CARDINAL;
  819.                         (* Returns the number of elements in the list.  *)
  820.  
  821. PROCEDURE WriteList     (f: tFile; List: tList; Proc: tProcOfFileAddress);
  822.                         (* Call Proc (f, e) for all elements of a list. *)
  823.                         (* e points to the current list element.        *)
  824.                         (* Can be used e. g. to print a list.           *)
  825.  
  826. END Lists.
  827. .)b
  828. .bp
  829. .sh 1 "Texts: texts are lists of strings (lines)"
  830. .sp
  831. .(b L
  832. .FT
  833. DEFINITION MODULE Texts;
  834.  
  835. TYPE tText              ;
  836.  
  837. PROCEDURE MakeText      (VAR Text: tText);
  838.                         (* Create an empty text.                        *)
  839.  
  840. PROCEDURE Append        (VAR Text: tText; VAR String: tString);
  841.                         (* Add a line at the beginning of text 'Text'.  *)
  842.  
  843. PROCEDURE Insert        (VAR Text: tText; VAR String: tString);
  844.                         (* Add a line at the end of the text 'Text'.    *)
  845.  
  846. PROCEDURE IsEmpty       (VAR Text: tText): BOOLEAN;
  847.                         (* Test whether a text 'Text' is empty.         *)
  848.  
  849. PROCEDURE WriteText     (f: tFile; Text: tText);
  850.                         (* Print the text 'Text' on the file 'f'.       *)
  851.  
  852. END Texts.
  853. .)b
  854. .sh 1 "Sets: sets for scalar values"
  855. .pp
  856. The following module provides operations on sets of scalar values. The
  857. elements of the sets can be of the types INTEGER, CARDINAL, CHAR, or of an
  858. enumeration type. Elements of type CHAR or of enumeration types have to be
  859. coerced to the type CARDINAL with the function ORD before use as a parameter
  860. of the functions below. The size of the sets, that is the range the elements
  861. must lie in, is not restricted. The elements can range from 0 to 'MaxSize', where
  862. 'MaxSize' is a parameter to the procedure MakeSet which dynamically allocates
  863. space for arbitrary large sets.
  864. .pp
  865. The sets are implemented as bit vectors (ARRAY OF BITSET) plus some
  866. additional information to improve performance. So don't worry about speed too much because 
  867. procedures like Select, Extract, or Card are quite efficient. They don't execute a loop
  868. over all potentially existing elements always. This happens only in the worst case.
  869. .sp
  870. .(b L
  871. .FT
  872. DEFINITION MODULE Sets;
  873.  
  874. TYPE tSet;
  875. TYPE ProcOfCard         = PROCEDURE (CARDINAL);
  876. TYPE ProcOfCardToBool   = PROCEDURE (CARDINAL): BOOLEAN;
  877.  
  878. PROCEDURE MakeSet       (VAR Set: tSet; MaxSize: CARDINAL);
  879. PROCEDURE ReleaseSet    (VAR Set: tSet);
  880. PROCEDURE Union         (VAR Set1: tSet; Set2: tSet);
  881. PROCEDURE Difference    (VAR Set1: tSet; Set2: tSet);
  882. PROCEDURE Intersection  (VAR Set1: tSet; Set2: tSet);
  883. PROCEDURE SymDiff       (VAR Set1: tSet; Set2: tSet);
  884. PROCEDURE Complement    (VAR Set: tSet);
  885. PROCEDURE Include       (VAR Set: tSet; Elmt: CARDINAL);
  886. PROCEDURE Exclude       (VAR Set: tSet; Elmt: CARDINAL);
  887. PROCEDURE Card          (VAR Set: tSet): CARDINAL;
  888. PROCEDURE Size          (VAR Set: tSet): CARDINAL;
  889. PROCEDURE Minimum       (VAR Set: tSet): CARDINAL;
  890. PROCEDURE Maximum       (VAR Set: tSet): CARDINAL;
  891. PROCEDURE Select        (VAR Set: tSet): CARDINAL;
  892. PROCEDURE Extract       (VAR Set: tSet): CARDINAL;
  893. PROCEDURE IsSubset      (Set1, Set2: tSet): BOOLEAN;
  894. PROCEDURE IsStrictSubset(Set1, Set2: tSet): BOOLEAN;
  895. PROCEDURE IsEqual       (VAR Set1, Set2: tSet): BOOLEAN;
  896. PROCEDURE IsNotEqual    (Set1, Set2: tSet): BOOLEAN;
  897. PROCEDURE IsElement     (Elmt: CARDINAL; VAR Set: tSet): BOOLEAN;
  898. PROCEDURE IsEmpty       (Set: tSet): BOOLEAN;
  899. PROCEDURE Forall        (Set: tSet; Proc: ProcOfCardToBool): BOOLEAN;
  900. PROCEDURE Exists        (Set: tSet; Proc: ProcOfCardToBool): BOOLEAN;
  901. PROCEDURE Exists1       (Set: tSet; Proc: ProcOfCardToBool): BOOLEAN;
  902. PROCEDURE Assign        (VAR Set1: tSet; Set2: tSet);
  903. PROCEDURE AssignElmt    (VAR Set: tSet; Elmt: CARDINAL);
  904. PROCEDURE AssignEmpty   (VAR Set: tSet);
  905. PROCEDURE ForallDo      (Set: tSet; Proc: ProcOfCard);
  906. PROCEDURE ReadSet       (f: tFile; VAR Set: tSet);
  907. PROCEDURE WriteSet      (f: tFile;     Set: tSet);
  908.  
  909. END Sets.
  910. .)b
  911. .pp
  912. Two parameters of type 'tSet' passed to one of the above procedures must have
  913. the same size, that is they must have been created by passing the same
  914. value 'MaxSize' to the procedure 'MakeSet'. A parameter representing an
  915. element (of type CARDINAL or equivalent) passed to one of the above
  916. procedures must have a value between 0 and 'MaxSize' of the
  917. involved set which is the other parameter passed. If the two conditions
  918. above, which can be verified at
  919. programming time, don't hold then strange things will happen,
  920. because there are no checks at run time, of course.
  921. .(b L
  922. .lp 
  923. The following table explains the semantics of the set operations:
  924. .sp 0.5
  925. .TS
  926. ;
  927. l l.
  928. Procedure    Semantics
  929. _
  930. MakeSet    allocates space for a set to hold elements
  931.      ranging from 0 to 'MaxSize'.
  932. ReleaseSet    releases the space taken by a set.
  933. Union    Set1 := Set1 \(cu Set2
  934. Difference    Set1 := Set1 - Set2
  935. Intersection    Set1 := Set1 \(ca Set2
  936. SymDiff    Set1 := Set1 \(xo Set2     (* corresponds to exclusive or *)
  937. Complement    Set := { 0 .. MaxSize } - Set
  938. Include    Set := Set \(cu { Elmt }
  939. Exclude    Set := Set - { Elmt }
  940. Card    returns number of elements in Set
  941. Size    returns 'MaxSize' given at creation time
  942. Minimum    returns smallest element x from Set
  943. Maximum    returns largest element x from Set
  944. Select    returns arbitrary element x from Set
  945. Extract    returns arbitrary element x from Set and removes it from Set
  946. IsSubset    Set1 \(ib Set2
  947. IsStrictSubset    Set1 \(sb Set2
  948. IsEqual    Set1 \(eq Set2
  949. IsNotEqual    Set1 \(!= Set2
  950. IsElement    Elmt \(mo Set
  951. IsEmpty    Set \(eq \(O/
  952. Forall    \(fa e \(mo Set : Proc (e)   (* predicate Proc must hold for all elements *)
  953. Exists    \(te e \(mo Set : Proc (e)   (* predicate Proc must hold for at least 1 element *)
  954. Exists1    | { e \(mo Set : Proc (e) } | \(eq 1
  955. Assign    Set1 := Set2
  956. AssignElmt    Set1 := { Elmt }
  957. AssignEmpty    Set1 := \(O/
  958. ForallDo    FOR e := 0 TO MaxSize DO
  959.           IF e \(mo Set THEN Proc (e); END;
  960.      END;
  961. ReadSet    read external representation of a set from file 'tFile'.
  962. WriteSet    write external representation of a set to file 'tFile'.
  963.      Example output: { 0 5 6 123}
  964. .TE
  965. .)b
  966. .sh 1 "SetsC: sets for scalar values"
  967. .pp
  968. This module provides the same procedures as the module Sets with the
  969. difference that all possible run time checks are performed.
  970. .sh 1 "Relations: binary relations between scalar values"
  971. .pp
  972. This module provides operations on binary relations between scalar values.
  973. The elements of the relations can be pairs of the types INTEGER, CARDINAL,
  974. CHAR, or of an enumeration type. Arguments of type CHAR or of enumeration
  975. types have to be coerced to the type CARDINAL with the function ORD before
  976. use as a parameter of the functions below. The size of the relations
  977. is not restricted. The size is a parameter to the procedure MakeRelation
  978. which dynamically allocates space for arbitrary large relations.
  979. .pp
  980. The relations are implemented as bit matrices or to be more exact as arrays
  981. of sets. Relations are viewed as sets of pairs. Therefore the set operations
  982. as defined above are also applicable for relations. The additional
  983. operations have the meaning known from theory.
  984. .sp
  985. .(b L
  986. .FT
  987. DEFINITION MODULE Relations;
  988.  
  989. TYPE tRelation;
  990. TYPE ProcOfIntInt       = PROCEDURE (INTEGER, INTEGER);
  991. TYPE ProcOfIntIntToBool = PROCEDURE (INTEGER, INTEGER): BOOLEAN;
  992.  
  993. PROCEDURE MakeRelation  (VAR Rel: tRelation; Size1, Size2: INTEGER);
  994. PROCEDURE ReleaseRelation (VAR Rel: tRelation);
  995. PROCEDURE Include       (VAR Rel: tRelation; e1, e2: INTEGER);
  996. PROCEDURE Exclude       (VAR Rel: tRelation; e1, e2: INTEGER);
  997. PROCEDURE IsElement     (e1, e2: INTEGER; Rel: tRelation): BOOLEAN;
  998. PROCEDURE IsRelated     (e1, e2: INTEGER; Rel: tRelation): BOOLEAN;
  999. PROCEDURE IsReflexive1  (e1: INTEGER; Rel: tRelation): BOOLEAN;
  1000. PROCEDURE IsSymmetric1  (e1, e2: INTEGER; Rel: tRelation): BOOLEAN;
  1001. PROCEDURE IsTransitive1 (e1, e2, e3: INTEGER; Rel: tRelation): BOOLEAN;
  1002. PROCEDURE IsReflexive   (Rel: tRelation): BOOLEAN;
  1003. PROCEDURE IsSymmetric   (Rel: tRelation): BOOLEAN;
  1004. PROCEDURE IsTransitive  (Rel: tRelation): BOOLEAN;
  1005. PROCEDURE IsEquivalence (Rel: tRelation): BOOLEAN;
  1006. PROCEDURE HasReflexive  (Rel: tRelation): BOOLEAN;
  1007. PROCEDURE IsCyclic      (Rel: tRelation): BOOLEAN;
  1008. PROCEDURE Closure       (VAR Rel: tRelation);
  1009. PROCEDURE AssignEmpty   (VAR Rel: tRelation);
  1010. PROCEDURE AssignElmt    (VAR Rel: tRelation; e1, e2: INTEGER);
  1011. PROCEDURE Assign        (VAR Rel1: tRelation; Rel2: tRelation);
  1012. PROCEDURE Union         (VAR Rel1: tRelation; Rel2: tRelation);
  1013. PROCEDURE Difference    (VAR Rel1: tRelation; Rel2: tRelation);
  1014. PROCEDURE Intersection  (VAR Rel1: tRelation; Rel2: tRelation);
  1015. PROCEDURE SymDiff       (VAR Rel1: tRelation; Rel2: tRelation);
  1016. PROCEDURE Complement    (VAR Rel: tRelation);
  1017. PROCEDURE IsSubset      (Rel1, Rel2: tRelation): BOOLEAN;
  1018. PROCEDURE IsStrictSubset (Rel1, Rel2: tRelation): BOOLEAN;
  1019. PROCEDURE IsEqual       (VAR Rel1, Rel2: tRelation): BOOLEAN;
  1020. PROCEDURE IsNotEqual    (Rel1, Rel2: tRelation): BOOLEAN;
  1021. PROCEDURE IsEmpty       (Rel: tRelation): BOOLEAN;
  1022. PROCEDURE Card          (VAR Rel: tRelation): INTEGER;
  1023. PROCEDURE Select        (VAR Rel: tRelation; VAR e1, e2: INTEGER);
  1024. PROCEDURE Extract       (VAR Rel: tRelation; VAR e1, e2: INTEGER);
  1025. PROCEDURE Forall        (Rel: tRelation; Proc: ProcOfIntIntToBool): BOOLEAN;
  1026. PROCEDURE Exists        (Rel: tRelation; Proc: ProcOfIntIntToBool): BOOLEAN;
  1027. PROCEDURE Exists1       (Rel: tRelation; Proc: ProcOfIntIntToBool): BOOLEAN;
  1028. PROCEDURE ForallDo      (Rel: tRelation; Proc: ProcOfIntInt);
  1029. PROCEDURE ReadRelation  (f: tFile; VAR Rel: tRelation);
  1030. PROCEDURE WriteRelation (f: tFile;     Rel: tRelation);
  1031.  
  1032. END Relations.
  1033. .)b
  1034. .bp
  1035. .sh 1 "IO: buffered input and output"
  1036. .pp
  1037. This module provides procedures for buffered input and output to files.
  1038. Io to and from terminals is possible too, because terminals are regarded as
  1039. special cases of files. There are procedures for binary io as well as for
  1040. text io, that is internal values are converted to their external
  1041. representation and vice versa.
  1042. .sp
  1043. .(b L
  1044. .FT
  1045. DEFINITION MODULE IO;
  1046.  
  1047. CONST   StdInput        ;   (* A pre-opened file for (terminal-)input.  *)
  1048. CONST   StdOutput       ;   (* A pre-opened file for (terminal-)output. *)
  1049. CONST   StdError        ;   (* A pre-opened file for (terminal-)output  *)
  1050.                             (*    of error messages.                    *)
  1051. TYPE    tFile           ;
  1052.  
  1053. PROCEDURE ReadOpen      (FileName: ARRAY OF CHAR): tFile;
  1054.                                                 (* open  input file     *)
  1055. PROCEDURE ReadClose     (f: tFile);             (* close input file     *)
  1056. PROCEDURE Read          (f: tFile; Buffer: ADDRESS; Size: CARDINAL): INTEGER;
  1057.                                                 (* binary               *)
  1058. PROCEDURE ReadC         (f: tFile): CHAR    ;   (* character            *)
  1059. PROCEDURE ReadI         (f: tFile): INTEGER ;   (* integer  number      *)
  1060. PROCEDURE ReadR         (f: tFile): REAL    ;   (* real     number      *)
  1061. PROCEDURE ReadB         (f: tFile): BOOLEAN ;   (* boolean              *)
  1062. PROCEDURE ReadN         (f: tFile; Base: INTEGER): INTEGER;
  1063.                                                 (* number of base 'Base'*)
  1064. PROCEDURE ReadS         (f: tFile; VAR s: ARRAY OF CHAR);
  1065.                                                 (* string               *)
  1066. .\"PROCEDURE ReadShort     (f: tFile): SHORTINT;   (* shortint number ?    *)
  1067. .\"PROCEDURE ReadLong      (f: tFile): LONGINT ;   (* longint  number ?    *)
  1068. .\"PROCEDURE ReadCard      (f: tFile): CARDINAL;   (* cardinal number ?    *)
  1069. PROCEDURE ReadNl        (f: tFile);             (* new line             *)
  1070. PROCEDURE UnRead        (f: tFile);             (* backspace 1 char.    *)
  1071.  
  1072. PROCEDURE EndOfLine     (f: tFile): BOOLEAN ;   (* end of line ?        *)
  1073. PROCEDURE EndOfFile     (f: tFile): BOOLEAN ;   (* end of file ?        *)
  1074.  
  1075. PROCEDURE WriteOpen     (FileName: ARRAY OF CHAR): tFile;
  1076.                                                 (* open  output file    *)
  1077. PROCEDURE WriteClose    (f: tFile);             (* close output file    *)
  1078. PROCEDURE WriteFlush    (f: tFile);             (* flush output buffer  *)
  1079. PROCEDURE Write         (f: tFile; Buffer: ADDRESS; Size: CARDINAL): INTEGER;
  1080.                                                 (* binary               *)
  1081. PROCEDURE WriteC        (f: tFile; c: CHAR);    (* character            *)
  1082. PROCEDURE WriteI        (f: tFile; n: INTEGER ; FieldWidth: CARDINAL);
  1083.                                                 (* integer  number      *)
  1084. PROCEDURE WriteR        (f: tFile; n: REAL; Before, After, Exp: CARDINAL);
  1085.                                                 (* real     number      *)
  1086. PROCEDURE WriteB        (f: tFile; b: BOOLEAN); (* boolean              *)
  1087. PROCEDURE WriteN        (f: tFile; n: LONGCARD; FieldWidth, Base: CARDINAL);
  1088.                                                 (* number of base 'Base'*)
  1089. PROCEDURE WriteS        (f: tFile; s: ARRAY OF CHAR); 
  1090.                                                 (* string               *)
  1091. .\"PROCEDURE WriteShort    (f: tFile; n: SHORTINT; FieldWidth: CARDINAL);
  1092. .\"                                                (* shortint number ?    *)
  1093. .\"PROCEDURE WriteLong     (f: tFile; n: LONGINT ; FieldWidth: CARDINAL);
  1094. .\"                                                (* longint  number ?    *)
  1095. .\"PROCEDURE WriteCard     (f: tFile; n: CARDINAL; FieldWidth: CARDINAL);
  1096. .\"                                                (* cardinal number ?    *)
  1097. PROCEDURE WriteNl       (f: tFile);             (* new line             *)
  1098.  
  1099. PROCEDURE CloseIO;                              (* close all files      *)
  1100. END IO.
  1101. .)b
  1102. .bp
  1103. Notes:
  1104. .ip "ReadOpen and WriteOpen"
  1105. Open the file whose name is given by the
  1106. parameter 'FileName' for input resp. output.
  1107. A file descriptor will be returned.
  1108. .ip "Read and Write"
  1109. Implement binary i/o for byte blocks.
  1110. .ip "ReadI, ReadR, ReadB, ReadN"
  1111. This procedures skip blanks before reading a value.
  1112. .ip "ReadR and WriteR"
  1113. .nf
  1114. \&'ReadR' reads real numbers according to the following syntax:
  1115.      [+|-] [digit* . digit*] [E [+|-] digit+]
  1116. \&'WriteR' writes real numbers similar to the Ada output routine PUT:
  1117.      Before . After E Exp
  1118. where Before, After, and Exp give the lengths of the fields. If Exp is 0
  1119. no exponent part is written.
  1120. .ip "ReadB and WriteB"
  1121. The external representation for boolean values are T for TRUE an F for
  1122. FALSE. On input every character other than T is interpreted as FALSE.
  1123. .ip "ReadN and WriteN"
  1124. Procedures for i/o of octal (Base = 8) or hexadecimal (Base = 16) numbers
  1125. for example. Base must have a value between 2 and 16.
  1126. .ip "ReadNl"
  1127. Read all characters up to and including the next end of line character.
  1128. .ip "EndOfLine"
  1129. Checks whether end of line has been reached. If this is the case the next
  1130. character to be read would be an end of line character.
  1131. .ip "EndOfFile"
  1132. Checks whether end of file has been reached. If this is the case none of the
  1133. input routines can yield any defined result.
  1134. .ip "WriteFlush"
  1135. The actual contents of the buffer for the specified file is written
  1136. unconditionally to the file.
  1137. .ip "WriteNl"
  1138. Writes an end of line character.
  1139. .ip "CloseIO"
  1140. This procedure has to be called at the end of every program that uses the
  1141. module IO. All buffers associated with files opened for output are flushed.
  1142. .sh 1 "StdIO: buffered IO for standard files"
  1143. .pp
  1144. This module provides the same procedures as the module IO with the
  1145. difference that the parameter 'f' to specify the file is missing.
  1146. The input (output) procedures use the file 'StdInput' ('StdOutput').
  1147. .bp
  1148. .sh 1 "Layout: more routines for input and output"
  1149. .sp
  1150. .(b L
  1151. .FT
  1152. DEFINITION MODULE Layout;
  1153.  
  1154. PROCEDURE WriteChar     (f: tFile; Ch: CHAR);
  1155.                         (* Printable characters are surrounded by       *)
  1156.                         (* quotes. Non-printable characters are written *)
  1157.                         (* as their internal code followed by a 'C'.    *)
  1158.  
  1159. PROCEDURE WriteSpace    (f: tFile);
  1160.                         (* Write a blank character to file 'f'.         *)
  1161.  
  1162. PROCEDURE WriteSpaces   (f: tFile; Count: INTEGER);
  1163.                         (* Write 'Count' blank characters to file 'f'.  *)
  1164.  
  1165. PROCEDURE ReadSpace     (f: tFile);
  1166.                         (* Skip one character of file 'f'.              *)
  1167.  
  1168. PROCEDURE ReadSpaces    (f: tFile; Count: INTEGER);
  1169.                         (* Skip 'Count' characters of file 'f'.         *)
  1170.  
  1171. PROCEDURE SkipSpaces    (f: tFile);
  1172.                         (* Skip as many blank characters as possible.   *)
  1173.  
  1174. END Layout.
  1175. .)b
  1176. .sh 1 "Positions: handling of source positions"
  1177. .pp
  1178. A simple representation of the position of tokens in a source file consisting of a line
  1179. and a column field. This module should be copied and tailored to the user's needs, if
  1180. necessary. Modifications may be necessary if the type SHORTCARD is to small to count
  1181. the lines or an extra field is needed to describe the source file.
  1182. .sp
  1183. .(b L
  1184. .FT
  1185. DEFINITION MODULE Positions;
  1186.  
  1187. TYPE      tPosition     = RECORD Line, Column: SHORTCARD; END;
  1188.  
  1189. VAR       NoPosition    : tPosition;
  1190.                         (* A default position (0, 0).                   *)
  1191.  
  1192. PROCEDURE Compare       (Position1, Position2: tPosition): INTEGER;
  1193.                         (* Returns -1 if Position1 < Position2.         *)
  1194.                         (* Returns  0 if Position1 = Position2.         *)
  1195.                         (* Returns  1 if Position1 > Position2.         *)
  1196.  
  1197. PROCEDURE WritePosition (File: tFile; Position: tPosition);
  1198.                         (* The 'Position' is printed on the 'File'.     *)
  1199.  
  1200. END Positions.
  1201. .)b
  1202. .bp
  1203. .sh 1 "Errors: error handler for parsers and compilers"
  1204. .pp
  1205. This module is needed by parsers generated with the parser generators
  1206. .i lalr
  1207. or
  1208. .i ell .
  1209. It can also b used to report error messages found during scanning or semantic analysis.
  1210. Note: This module has to be copied, too, if the module
  1211. .i Positions
  1212. is copied and modified because it depends upon this module.
  1213. .sp
  1214. .(l L
  1215. .FT
  1216. DEFINITION MODULE Errors;
  1217.  
  1218. CONST
  1219.    NoText               = 0     ;
  1220.    SyntaxError          = 1     ;       (* error codes          *)
  1221.    ExpectedTokens       = 2     ;
  1222.    RestartPoint         = 3     ;
  1223.    TokenInserted        = 4     ;
  1224.    WrongParseTable      = 5     ;
  1225.    OpenParseTable       = 6     ;
  1226.    ReadParseTable       = 7     ;
  1227.    TooManyErrors        = 8     ;
  1228.  
  1229.    Fatal                = 1     ;       (* error classes        *)
  1230.    Restriction          = 2     ;
  1231.    Error                = 3     ;
  1232.    Warning              = 4     ;
  1233.    Repair               = 5     ;
  1234.    Note                 = 6     ;
  1235.    Information          = 7     ;
  1236.  
  1237.    None                 = 0     ;
  1238.    Integer              = 1     ;       (* info classes         *)
  1239.    Short                = 2     ;
  1240.    Long                 = 3     ;
  1241.    Real                 = 4     ;
  1242.    Boolean              = 5     ;
  1243.    Character            = 6     ;
  1244.    String               = 7     ;
  1245.    Array                = 8     ;
  1246.    Set                  = 9     ;
  1247.    Ident                = 10    ;
  1248. .bp
  1249. VAR       Exit          : PROC;
  1250.                         (* Refers to a procedure that specifies         *)
  1251.                         (* what to do if 'ErrorClass' = Fatal.          *)
  1252.                         (* Default: terminate program execution.        *)
  1253.  
  1254. PROCEDURE StoreMessages (Store: BOOLEAN);
  1255.                         (* Messages are stored if 'Store' = TRUE        *)
  1256.                         (* for printing with the routine 'WriteMessages'*)
  1257.                         (* otherwise they are printed immediately.      *)
  1258.                         (* If 'Store'=TRUE the message store is cleared.*)
  1259.  
  1260. PROCEDURE ErrorMessage  (ErrorCode, ErrorClass: CARDINAL; Position: tPosition);
  1261.                         (* Report a message represented by an integer   *)
  1262.                         (* 'ErrorCode' and classified by 'ErrorClass'.  *)
  1263.  
  1264. PROCEDURE ErrorMessageI (ErrorCode, ErrorClass: CARDINAL; Position: tPosition;
  1265.                          InfoClass: CARDINAL; Info: ADDRESS);
  1266.                         (* Like the previous routine with additional    *)
  1267.                         (* information of type 'InfoClass' at the       *)
  1268.                         (* address 'Info'.                              *)
  1269.  
  1270. PROCEDURE Message       (ErrorText: ARRAY OF CHAR; ErrorClass: CARDINAL;
  1271.                          Position: tPosition);
  1272.                         (* Report a message represented by a string     *)
  1273.                         (* 'ErrorText' and classified by 'ErrorClass'.  *)
  1274.  
  1275. PROCEDURE MessageI      (ErrorText: ARRAY OF CHAR; ErrorClass: CARDINAL;
  1276.                          Position: tPosition; InfoClass: CARDINAL; Info: ADDRESS);
  1277.                         (* Like the previous routine with additional    *)
  1278.                         (* information of type 'InfoClass' at the       *)
  1279.                         (* address 'Info'.                              *)
  1280.  
  1281. PROCEDURE WriteMessages (File: tFile);
  1282.                         (* The stored messages are sorted by their      *)
  1283.                         (* source position and printed on 'File'.       *)
  1284.  
  1285. END Errors.
  1286. .)l
  1287. .bp
  1288. .sh 1 "Source: provides input for scanners"
  1289. .pp
  1290. This module is needed by scanners generated with the scanner generator
  1291. .i rex .
  1292. .sp
  1293. .(b L
  1294. .FT
  1295. DEFINITION MODULE Source;
  1296.  
  1297. PROCEDURE BeginSource (FileName: ARRAY OF CHAR): tFile;
  1298.  
  1299.    (*
  1300.       BeginSource is called from the scanner to open files.
  1301.       If not called then input is read form standard input.
  1302.    *)
  1303.  
  1304. PROCEDURE GetLine (File: tFile; Buffer: ADDRESS; Size: CARDINAL): INTEGER;
  1305.  
  1306.    (*
  1307.       GetLine is called to fill a buffer starting at address 'Buffer'
  1308.       with a block of maximal 'Size' characters. Lines are terminated
  1309.       by newline characters (ASCII = 0xa). GetLine returns the number
  1310.       of characters transferred. Reasonable block sizes are between 128
  1311.       and 2048 or the length of a line. Smaller block sizes -
  1312.       especially block size 1 - will drastically slow down the scanner.
  1313.    *)
  1314.  
  1315. PROCEDURE CloseSource (File: tFile);
  1316.  
  1317.    (*
  1318.       CloseSource is called from the scanner at end of file or
  1319.       at end of input, respectively. It can be used to close files.
  1320.    *)
  1321.  
  1322. END Source.
  1323. .)b
  1324. .bp
  1325. .sh 1 "Sort: quicksort for arrays with elements of arbitrary type"
  1326. .sp
  1327. .(b L
  1328. .FT
  1329. DEFINITION MODULE Sort;
  1330.  
  1331. TYPE tProcIntIntBool    = PROCEDURE (INTEGER, INTEGER): BOOLEAN;
  1332. TYPE tProcIntInt        = PROCEDURE (INTEGER, INTEGER);
  1333.  
  1334. PROCEDURE Sort (Lwb, Upb: INTEGER; IsLess: tProcIntIntBool; Swap: tProcIntInt);
  1335.  
  1336.         (* Sort data from the indices 'Lwb' to 'Upb' using quicksort.   *)
  1337.         (* The procedures 'IsLess' and 'Swap' are used to compare and   *)
  1338.         (* exchange two data elements.                                  *)
  1339.  
  1340. END Sort.
  1341. .)b
  1342. .sh 1 "General: miscellaneous functions"
  1343. .sp
  1344. .(b L
  1345. .FT
  1346. DEFINITION MODULE General;
  1347.  
  1348. PROCEDURE Min           (a, b: INTEGER)                 : INTEGER;
  1349.                         (* Returns the minimum of 'a' and 'b'.          *)
  1350.  
  1351. PROCEDURE Max           (a, b: INTEGER)                 : INTEGER;
  1352.                         (* Returns the maximum of 'a' and 'b'.          *)
  1353.  
  1354. PROCEDURE Log2          (x: LONGINT)                    : CARDINAL;
  1355.                         (* Returns the logarithm to the base 2 of 'x'.  *)
  1356.  
  1357. PROCEDURE Exp2          (x: CARDINAL)                   : LONGINT;
  1358.                         (* Returns 2 to the power of 'x'.               *)
  1359.  
  1360. PROCEDURE AntiLog       (x: LONGINT)                    : CARDINAL;
  1361.                         (* Returns the number of the lowest bit set in 'x'. *)
  1362.  
  1363. PROCEDURE Exp10         (x: INTEGER)                    : REAL;
  1364.                         (* Returns 10 to the power of 'x'.              *)
  1365.  
  1366. END General.
  1367. .)b
  1368. .bp
  1369. .sh 1 "System: machine dependent code"
  1370. .pp
  1371. This module provides a few machine dependent operations.
  1372. .sp
  1373. .(l L
  1374. .FT
  1375. FOREIGN MODULE System;
  1376.  
  1377. CONST   cMaxFile    = 32;
  1378. CONST   StdInput        ;   (* A pre-opened file for (terminal-)input.  *)
  1379. CONST   StdOutput       ;   (* A pre-opened file for (terminal-)output. *)
  1380. CONST   StdError        ;   (* A pre-opened file for (terminal-)output  *)
  1381.                             (*    of error messages.                    *)
  1382.  
  1383. TYPE    tFile           ;
  1384.  
  1385.                         (* binary IO            *)
  1386.  
  1387. PROCEDURE OpenInput     (VAR FileName: ARRAY OF CHAR): tFile;
  1388.                         (* Opens the file whose name is given by the    *)
  1389.                         (* parameter 'FileName' for input.              *)
  1390.                         (* Returns a file descriptor.                   *)
  1391.  
  1392. PROCEDURE OpenOutput    (VAR FileName: ARRAY OF CHAR): tFile;
  1393.                         (* Opens the file whose name is given by the    *)
  1394.                         (* parameter 'FileName' for output.             *)
  1395.                         (* Returns a file descriptor.                   *)
  1396.  
  1397. PROCEDURE Read          (File: tFile; Buffer: ADDRESS; Size: CARDINAL): INTEGER;
  1398.                         (* Reads 'Size' bytes from file 'tFile' and     *)
  1399.                         (* stores them in a buffer starting at address  *)
  1400.                         (* 'Buffer'.                                    *)
  1401.                         (* Returns the number of bytes actually read.   *)
  1402.  
  1403. PROCEDURE Write         (File: tFile; Buffer: ADDRESS; Size: CARDINAL): INTEGER;
  1404.                         (* Writes 'Size' bytes from a buffer starting   *)
  1405.                         (* at address 'Buffer' to file 'tFile'.         *)
  1406.                         (* Returns the number of bytes actually written.*)
  1407.  
  1408. PROCEDURE Close         (File: tFile);
  1409.                         (* Closes file 'tFile'.                         *)
  1410.  
  1411. PROCEDURE IsCharacterSpecial (File: tFile): BOOLEAN;
  1412.                         (* Returns TRUE when file 'tFile' is connected  *)
  1413.                         (* to a character device like a terminal.       *)
  1414.  
  1415.                         (* calls other than IO  *)
  1416.  
  1417. PROCEDURE SysAlloc      (ByteCount: LONGINT): ADDRESS;
  1418.                         (* Returns a pointer to dynamically allocated   *)
  1419.                         (* memory space of size 'ByteCount' bytes.      *)
  1420.                         (* Returns NIL if space is exhausted.           *)
  1421.  
  1422. PROCEDURE Time          (): LONGINT;
  1423.                         (* Returns consumed cpu-time in milliseconds.   *)
  1424.  
  1425. PROCEDURE GetArgCount   (): CARDINAL;
  1426.                         (* Returns number of arguments.                 *)
  1427.  
  1428. PROCEDURE GetArgument   (ArgNum: CARDINAL; VAR Argument: ARRAY OF CHAR);
  1429.                         (* Stores a string-valued argument whose index  *)
  1430.                         (* is 'ArgNum' in the memory area 'Argument'.   *)
  1431.  
  1432. PROCEDURE PutArgs       (Argc: CARDINAL; Argv: ADDRESS);
  1433.                         (* Dummy procedure that passes the values       *)
  1434.                         (* 'argc' and 'argv' from Modula-2 to C.        *)
  1435.  
  1436. PROCEDURE ErrNum        (): INTEGER;
  1437.                         (* Returns the current system error code.       *)
  1438.  
  1439. PROCEDURE System        (VAR String: ARRAY OF CHAR): INTEGER;
  1440.                         (* Executes an operating system command given   *)
  1441.                         (* as the string 'String'. Returns an exit or   *)
  1442.                         (* return code.                                 *)
  1443.  
  1444. PROCEDURE Exit          (Status: INTEGER);
  1445.                         (* Terminates program execution and passes the  *)
  1446.                         (* value 'Status' to the operating system.      *)
  1447.  
  1448. END System.
  1449. .)l
  1450. .sh 1 "Checks: checks for system calls"
  1451. .sp
  1452. .(b L
  1453. .FT
  1454. DEFINITION MODULE Checks;
  1455.  
  1456. PROCEDURE ErrorCheck    (s: ARRAY OF CHAR; n: INTEGER);
  1457.                         (* The parameter 'n' should be a value returned *)
  1458.                         (* from a system call. If it is negative the    *)
  1459.                         (* string 's', the value of 'n', and the value  *)
  1460.                         (* returned by 'ErrNum' are printed on the file *)
  1461.                         (* 'StdError'.                                  *)
  1462.  
  1463. END Checks.
  1464. .)b
  1465. .lp
  1466. Example:
  1467. .sp
  1468. .(b L
  1469. .FT
  1470.    VAR n: INTEGER;
  1471.  
  1472.    n := OpenInput ("DataFile");
  1473.    ErrorCheck ("error at open of DataFile", n);
  1474. .)b
  1475. .bp
  1476. .sh 1 "Times: access to cpu-time"
  1477. .sp
  1478. .(b L
  1479. .FT
  1480. DEFINITION MODULE Times;
  1481.  
  1482. PROCEDURE CpuTime       (): LONGINT;
  1483.                         (* Returns the sum of user time and system time *)
  1484.                         (* since the start of the program in milli-secs.*)
  1485.  
  1486. PROCEDURE StepTime      (): LONGINT;
  1487.                         (* Returns the sum of user time and system time *)
  1488.                         (* since the last call to 'StepTime' in milli-  *)
  1489.                         (* seconds. The first call yields the same      *)
  1490.                         (* result as a call to 'CpuTime'.               *)
  1491.  
  1492. PROCEDURE WriteStepTime (Text: ARRAY OF CHAR);
  1493.                         (* Writes a line consisting of the string       *)
  1494.                         (* 'Text' and the value obtained from a call to *)
  1495.                         (* 'StepTime' to the file 'StdOutput'.          *)
  1496.  
  1497. END Times.
  1498. .)b
  1499. .sh 1 "An Example: Text represented as a List of Strings"
  1500. .sp
  1501. .(b L
  1502. .FT
  1503. MODULE Example;
  1504.  
  1505. FROM SYSTEM       IMPORT ADDRESS;
  1506. FROM IO           IMPORT StdInput, StdOutput, EndOfFile;
  1507. FROM Strings      IMPORT tString, ReadL, WriteL;
  1508. FROM StringMem    IMPORT tStringRef, PutString, GetString;
  1509. FROM Lists        IMPORT tList, MakeList, Append, IsEmpty, Head, Tail;
  1510.  
  1511. VAR String      : tString;
  1512. VAR Ref         : tStringRef;
  1513. VAR Text        : tList;
  1514.  
  1515. BEGIN
  1516.    MakeList (Text);                     (* start with empty list        *)
  1517.    WHILE NOT EndOfFile (StdInput) DO    (* process complete input file  *)
  1518.       ReadL (StdInput, String);         (* read one line                *)
  1519.       Ref := PutString (String);        (* store it in string memory    *)
  1520.       Append (Text, ADDRESS (Ref));     (* append it to current text    *)
  1521.    END;
  1522.     
  1523.    WHILE NOT IsEmpty (Text) DO          (* process complete text        *)
  1524.       Ref := tStringRef (Head (Text));  (* get current first line       *)
  1525.       GetString (Ref, String);          (* fetch string from memory     *)
  1526.       WriteL (StdOutput, String);       (* print string in one line     *)
  1527.       Tail (Text);                      (* continue with remaining text *)
  1528.    END;
  1529. END Example.
  1530. .)b
  1531. .\ .fi
  1532. .\ .sp
  1533. .\ .b
  1534. .\ .sz 12
  1535. .\ .(x
  1536. .\     References
  1537. .\ .)x
  1538. .\ .[]
  1539. .bp 1
  1540. .lp
  1541. .b Contents
  1542. .sp
  1543. .xp
  1544.